Configuring TLS Certificate Contexts

The TLS Contexts table lets you configure up to 100 TLS Contexts. A TLS Context defines Transport Layer Security (TLS) settings (e.g., TLS certificates). The TLS protocol provides confidentiality, integrity, and authenticity between two communicating applications over TCP/IP.

You can use TLS for the following:

To secure device management communication, for example, HTTPS-based Web sessions, Telnet sessions and SSH sessions.
To secure SIP signaling connections, referred to as SIP Secure (SIPS) or SIP over TLS.
To secure various other network applications supported by the device, for example, communication with a remote LDAP server used for LDAP-based user management authentication and authorization.

The device is shipped with a default TLS Context (Index #0 and named "default"), which includes a self-generated random private key and a self-signed server certificate. The Common Name (CN or subject name) of the default certificate is "ACL_nnnnnnn", where nnnnnnn denotes the serial number of the device.

The default TLS Context cannot be deleted.
For secure management through the default management network interface (i.e., OAMP Application Type in the IP Interfaces table), the device uses the default TLS Context. However, for secure Web and REST access using the additional management interfaces configured in the Web Interfaces table (see Configuring Web Interfaces), you can use any TLS Context.
If a TLS Context for an existing TLS connection is changed during the call by the user agent, the device ends the connection.
For more information on secured management, see Configuring Secured (HTTPS) Web.

You can configure each TLS Context with the following TLS settings:

TLS version (TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3).
DTLS version (DTLS 1.0 and DTLS 1.2).
TLS cipher suites for server and client roles (per OpenSSL syntax).
Diffie-Hellman (DH) key size used by the device if it acts as a TLS server and DH is used for key exchange.
Online Certificate Status Protocol (OCSP). Some Public-Key Infrastructures (PKI) can revoke a certificate after it has been issued. You can configure the device to check if a peer's certificate has been revoked, using OCSP. When OCSP is enabled, the device queries the OCSP server for revocation information whenever a peer certificate is received (TLS client mode, or TLS server mode with mutual authentication).
The device doesn't query OCSP for its own certificate.
Some PKIs do not support OCSP, but generate Certificate Revocation Lists (CRLs). For such scenarios, set up an OCSP server such as OCSPD.
Private key - externally created and then uploaded to device.
Different levels of security strength (key size) per TLS certificate.
X.509 certificates - self-signed certificates or signed as a result of a certificate signing request (CSR).
Trusted root certificate authority (CA) store (for validating certificates).
When creating a TLS Context, you should create a certificate as described in Creating Self-Signed Certificates for TLS Contexts, and then check that the certificate is "Ok" as described in Viewing Certificate Information.
For secure SIP messaging (SIP Secure or SIPS) using TLS, see TLS for SIP Clients (two-way authentication) and Configuring TLS for Secured SIP.
To map an SNI (hostname in 'server_name' extension of "client hello" message) to a TLS Context, see Configuring SNI-to-TLS Mapping.
To configure the device to periodically check the validation date of installed TLS server certificates of TLS Contexts, see Configuring TLS Server Certificate Expiry Check.

The following procedure describes how to configure a TLS Context through the Web interface. You can also configure it through ini file [TLSContexts] or CLI (configure network > tls).

To configure a TLS Context:
1. Open the TLS Contexts table (Setup menu > IP Network tab > Security folder > TLS Contexts).
2. Click New to add a new TLS Context or Edit to modify the default TLS Context at Index 0; the following dialog box appears:

3. Configure the TLS Context according to the parameters described in the table below.
4. Click Apply.

TLS Contexts Parameter Descriptions

Parameter

Description

General

'Index'

tls

[Index]

Defines an index number for the new table row.

Note:

Each row must be configured with a unique index.
Index 0 ("default") is the default TLS Context.

'Name'

name

[Name]

Defines a descriptive name, which is used when associating the row in other tables.

The valid value is a string of up to 31 characters.

Note:

The parameter value cannot contain a forward slash (/).
The default TLS Context (Index 0) is named "default".

'TLS Version'

tls-version

[TLSVersion]

Defines the supported TLS protocol version. Clients attempting to communicate with the device using a different TLS version are rejected.

[0] Any TLS1.x = TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3 are supported.
[1] TLSv1.0 = Only TLS 1.0.
[2] TLSv1.1 = Only TLS 1.1.
[3] TLSv1.0 and TLSv1.1 = Only TLS 1.0 and TLS 1.1.
[4] TLSv1.2 = Only TLS 1.2.
[6] TLSv1.1 and TLSv1.2 = Only TLS 1.1 and TLS 1.2.
[7] TLSv1.0 TLSv1.1 and TLSv1.2 = Only TLS 1.0, TLS 1.1, and TLS 1.2.
[8] TLSv1.3 = Only TLS 1.3.
[12] TLSv1.2 and TLSv1.3 = (Default) Only TLS 1.2 and TLS 1.3.
[14] TLSv1.1 TLSv1.2 and TLSv1.3 = Only TLS 1.1, TLS 1.2, and TLS 1.3.
[15] TLSv1.0 TLSv1.1 TLSv1.2 and TLSv1.3 = Only TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3.

'DTLS Version'

[DTLSVersion]

Defines the Datagram Transport Layer Security (DTLS) version, which is used to negotiate keys for WebRTC calls.

[0] DTLSv1.0 and DTLSv1.2 (default)
[1] DTLSv1.0
[2] DTLSv1.2

For more information on WebRTC, see WebRTC.

Note: The parameter is applicable only to the SBC application.

'Cipher Server'

ciphers-server

[ServerCipherString]

Defines the supported cipher suite for the TLS server (in OpenSSL cipher list format) when the TLS version is 1.2 or earlier.

For possible values and additional details, visit the OpenSSL website. The default is "DEFAULT".

Note: The parameter is applicable only to TLS 1.2 and earlier.

'Cipher Client'

ciphers-client

[ClientCipherString]

Defines the supported cipher suite for TLS clients when the TLS version is 1.2 or earlier.

For possible values and additional details, visit the OpenSSL website. The default is "DEFAULT".

Note: The parameter is applicable only to TLS 1.2 and earlier.

'Cipher Server TLS1.3'

ciphers-server-tls13

[ServerCipherTLS13String]

Defines the supported cipher suite for the TLS 1.3 server (in OpenSSL cipher list format).

For possible values and additional details, visit the OpenSSL website. The default is "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256".

Note: The parameter is applicable only to TLS 1.3.

'Cipher Client TLS1.3'

ciphers-client-tls13

[ClientCipherTLS13String]

Defines the supported cipher suite for TLS 1.3 clients.

For possible values and additional details, visit the OpenSSL website. The default is "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256".

Note: The parameter is applicable only to TLS 1.3.

'Key Exchange Groups'

key-exchange-groups

[KeyExchangeGroups]

Defines the groups that are supported for key exchange, ordered from most preferred to least preferred.

The valid value is any combination of the following strings:

X25519
P-256
P-384
X448

The default is "X25519:P-256:P-384:X448" (without quotation marks).

When configuring the parameter with multiple values, separate each with a colon. In addition, the order of the values determines the group preference. For example, the value "P-384:P-256:X25519" (without quotation marks) gives preference to P-384. The TLS client uses the first configured value (e.g., P-384) as its group trial, while the TLS server uses the whole list to try and match the client’s trial.

Note: The parameter is applicable to all TLS versions.

'Strict Certificate Extension Validation'

require-strict-cert

[RequireStrictCert]

Enables the validation of the extensions (keyUsage and extendedKeyUsage) of peer certificates. The validation ensures that the signing CA is authorized to sign certificates and that the end-entity certificate is authorized to negotiate a secure TLS connection.

[0] Disable (default)
[1] Enable

'DH Key Size'

dh-key-size

[DHKeySize]

Defines the Diffie-Hellman (DH) key size (in bits). DH is an algorithm used mainly for exchanging cryptography keys used in symmetric encryption algorithms such as AES.

[1024] 1024 - Not Recommended
[2048] 2048 (default)

Note: 1024-bit key size is not recommended.

'TLS Renegotiation'

tls-renegotiation

[TlsRenegotiation]

Enables TLS renegotiations (handshakes) initiated by the client (peer) with the device.

[0] Disable = The device blocks client-initiated TLS renegotiations and allows only one TLS handshake process. This is useful, for example, for preventing Denial-of-Service (DoS) attacks on the device caused by multiple TLS renegotiations per second by an attacker.
[1] Enable (default)

'Use default CA Bundle'

trusted-root default-ca-bundle

[UseDefaultCABundle]

Enables the use of the default list of trusted root certificate authorities (CAs).

0] Disable (default)
[1] Enable

To view the default list of CAs, see Viewing Default Certificate Authorities.

Note:

You can only use the default CAs for TLS Context IDs 0 through 4.

OCSP

 

'OCSP Server'

ocsp-server

[OcspEnable]

Enables certificate checking using Online Certificate Status Protocol (OCSP).

[0] Disable (default)
[1] Enable

'OCSP Interface'

ocsp-interface

[OcspInterface]

 

Assigns an IP Interface for communication with the OCSP server.

By default, the OAMP interface is assigned (Index 0 "O+M+C").

To configure IP Interfaces, see Configuring IP Network Interfaces.

Note: The addresses of the IP Interface and the OCSP servers (see 'Primary OCSP Server' and 'Secondary OCSP Server' parameters below) must be of the same IP version (IPv4 or IPv6).

'Primary OCSP Server'

ocsp-server-primary

[OcspServerPrimary]

Defines the address (IPv4 or IPv6, or FQDN) of the primary OCSP server.

The default is 0.0.0.0.

Note:

The address configured for the 'Primary OCSP Server' parameter and the optional 'Secondary OCSP Server' parameter must be of the same IP version (IPv4 or IPv6).
An FQDN address is supported only by TLS Contexts that are used for SIP connections. If you configure the parameter with an FQDN and the TLS Context is used for non-SIP connections, the certificate is not checked by the OCSP server.

'Secondary OCSP Server'

ocsp-server-secondary

[OcspServerSecondary]

Defines the address (IPv4 or IPv6, or FQDN) of the secondary OCSP server (optional).

The default is 0.0.0.0.

Note:

The address configured for the 'Primary OCSP Server' parameter and the 'Secondary OCSP Server' parameter must be of the same IP version (IPv4 or IPv6).
An FQDN address is supported only by TLS Contexts that are used for SIP connections. If you configure the parameter with an FQDN and the TLS Context is used for non-SIP connections, the certificate is not checked by the OCSP server.

'OCSP Port'

ocsp-port

[OcspServerPort]

Defines the OCSP server's TCP port number.

The default port is 2560.

'OCSP Default Response'

ocsp-default-response

[OcspDefaultResponse]

Defines if the device allows or rejects peer certificates if it cannot connect to the OCSP server.

[0] Reject (default)
[1] Allow